home *** CD-ROM | disk | FTP | other *** search
/ Mac Magazin/MacEasy 14 / Mac Magazin and MacEasy Magazine CD - Issue 14.iso / Wissenschaft & Technik / Tools Plus 2.6.1 Evaluation Kit / Tools Plus 2.6.1 / User Manual / 11-Pop-Up Menus (2 of 2) < prev    next >
INI File  |  1994-09-17  |  18KB  |  297 lines
  1. [Display using Monaco 9]
  2.  
  3.  
  4. InsertPopUpItem
  5. ```````````````
  6. Insert an item into an existing pop-up menu.
  7.  
  8.    pascal void InsertPopUpItem (short MenuNumber, short ItemNumber,
  9.                  Boolean EnabledFlag, Str255 MenuText);
  10.  
  11.    procedure InsertPopUpItem (MenuNumber, ItemNumber: INTEGER;
  12.                  EnabledFlag: BOOLEAN; MenuText: STRING);
  13.  
  14.   MenuNumber specifies the pop-up menu number (from 1 to 255) that is affected in the current window.  If the current window doesn’t belong to your application, or if the specified pop-up menu doesn’t exist, InsertPopUpItem does nothing.
  15.  
  16.   ItemNumber specifies the pop-up menu’s item number (from 1 to 255) where the item is inserted.  If the pop-up menu item does not exist in the specified pop-up menu, InsertPopUpItem does nothing.  InsertPopUpItem will append one item to the end of a pop-up menu if the ItemNumber equals the current number of items plus 1.
  17.  
  18.   EnabledFlag specifies whether the item is enabled or disabled.  In the enabled state, the item can be selected whereas in the disabled state, the item is dimmed and cannot be selected by the user.  The two constants that can be used for this purpose are enabled and disabled.  An entire pop-up menu and individual pop-up menu items can be enabled and disabled by using the EnablePopUp procedure.
  19.  
  20.   MenuText is the name of the item.  Certain metacharacters are recognized by Tools Plus to provide special instructions to the Menu Manager.  You may choose to include or exclude these characters within MenuText, however, you should be aware of their effects.  See the PopUpMenu procedure for details on metacharacters.
  21.  
  22.   When the item is inserted, all existing items starting at ItemNumber are pushed down one space to make room for the new item.  This means that their item number will be changed.  The new item is inserted at the location specified by ItemNumber.  The main use for this procedure is to let your application maintain a dynamic menu, such as a list of open document names.
  23.  
  24. Note: The Macintosh’s Menu Manager allows only the first 31 items of a
  25.       pop-up menu to be disabled individually.  The entire pop-up menu,
  26.       however, can always be disabled.
  27.  
  28.   CONST                    {Menu and Menu Item status }
  29.     enabled       = true;  {enable the menu/item      }
  30.     disabled      = false; {disable the menu/item     }
  31.     mDividingLine = ‘-’;   {Dividing line             }
  32.  
  33. ------------------------------------------------------------------------
  34.  
  35. RemovePopUp
  36. ```````````
  37. Delete a pop-up menu and its associated items, or delete an individual pop-up menu item.
  38.  
  39.    pascal void RemovePopUp (short MenuNumber, short ItemNumber);
  40.  
  41.    procedure RemovePopUp (MenuNumber, ItemNumber: INTEGER);
  42.  
  43.   MenuNumber specifies the pop-up menu number (from 1 to 255) that is affected in the current window.  If the current window doesn’t belong to your application, or if the specified pop-up menu doesn’t exist, RemovePopUp does nothing.
  44.  
  45.   ItemNumber specifies the pop-up menu’s item number (from 1 to 255) that is deleted.  If ItemNumber is zero (0), RemovePopUp refers to the pop-up menu and all its associated items.  If ItemNumber is not zero and it does not exist, RemovePopUp does nothing.
  46.  
  47. Note: Use RemovePopUp to maintain a dynamic menu, such as a list of
  48.       available font sizes.  Do not use it to make items unavailable.
  49.       Instead, disable items with EnablePopUp.
  50.  
  51. ------------------------------------------------------------------------
  52.  
  53. GetPopUpString
  54. ``````````````
  55. Get a pop-up menu item’s text without the metacharacters.
  56.  
  57.    pascal void GetPopUpString (short MenuNumber, short ItemNumber,
  58.                  Str255 MenuText);
  59.  
  60.    procedure GetPopUpString (MenuNumber, ItemNumber: INTEGER;
  61.                  var MenuText: STR255);
  62.  
  63.   MenuNumber specifies the pop-up menu number (from 1 to 255) that is affected in the current window.
  64.  
  65.   ItemNumber specifies the pop-up menu item number (from 1 to 255) from which the text is obtained.
  66.  
  67.   MenuText specifies the pop-up menu item’s name.  If the specified pop-up menu does not exist in the current window, or the specified item doesn’t exist, MenuText returns as a null string (length is zero).  Note that the string will return as a single space (‘ ’) if a null string was specified when the item was created (this happens automatically to prevent the Menu Manager from crashing).
  68.  
  69. ------------------------------------------------------------------------
  70.  
  71. RenamePopUp
  72. ```````````
  73. Rename an existing pop-up menu item.
  74.  
  75.    pascal void RenamePopUp (short MenuNumber, short ItemNumber,
  76.                  Str255 MenuText);
  77.  
  78.    procedure RenamePopUp (MenuNumber, ItemNumber: INTEGER;
  79.                  MenuText: STRING);
  80.  
  81.   MenuNumber specifies the pop-up menu number (from 1 to 255) that is affected in the current window.  If the current window doesn’t belong to your application, or if the specified pop-up menu doesn’t exist, RenamePopUp does nothing.
  82.  
  83.   ItemNumber specifies the menu item number (from 1 to 255) which is changed.  If the item number does not exist within the pop-up menu specified by MenuNumber, RenamePopUp does nothing.
  84.  
  85.   MenuText specifies the pop-up menu item’s new name.  The item’s state (enabled/disabled), style (bold, underline, etc.), icon and command key equivalent are not changed.  Metacharacters are not interpreted by this procedure.
  86.  
  87.   RenamePopUp does not change the pop-up menu’s title.  If the pop-up menu’s title must be changed, the affected pop-up menu must be removed with the RemovePopUp procedure, then re-created as required by using the NewPopUp procedure.
  88.  
  89. ------------------------------------------------------------------------
  90.  
  91. EnablePopUp
  92. ```````````
  93. Enable or disable a pop-up menu or pop-up menu item.
  94.  
  95.    pascal void EnablePopUp (short MenuNumber, short ItemNumber,
  96.                  Boolean EnabledFlag);
  97.  
  98.    procedure EnablePopUp (MenuNumber, ItemNumber: INTEGER;
  99.                  EnabledFlag: BOOLEAN);
  100.  
  101.   MenuNumber specifies the pop-up menu number (from 1 to 255) that is affected in the current window.  If the current window doesn’t belong to your application, or if the specified pop-up menu doesn’t exist, EnablePopUp does nothing.
  102.  
  103.   ItemNumber specifies the menu item number (from 1 to 255) which is enabled/disabled.  A value of zero (0) affects the entire pop-up menu.  If ItemNumber is not zero and the item number does not exist within the menu specified by MenuNumber, EnablePopUp does nothing.
  104.  
  105.   EnabledFlag specifies whether the pop-up menu/item is enabled or disabled.  In the enabled state, the menu/item can be selected.  The two constants that can used for this purpose are enabled and disabled.  If the ItemNumber is zero, the entire pop-up menu is disabled and the items cannot be viewed.  When the pop-up menu later becomes enabled, all items in the pop-up menu assume their correct enabling/disabling as specified by your application.
  106.  
  107. Note: The Macintosh’s Menu Manager allows only the first 31 items of a
  108.       pop-up menu to be disabled individually.  The entire pop-up menu,
  109.       however, can always be disabled.
  110.  
  111.   CONST                    {Menu and Menu Item status }
  112.     enabled       = true;  {enable the menu/item      }
  113.     disabled      = false; {disable the menu/item     }
  114.  
  115. ------------------------------------------------------------------------
  116.  
  117. PopUpIsEnabled
  118. ``````````````
  119. Determine if a pop-up menu is enabled or disabled.
  120.  
  121.    pascal Boolean PopUpIsEnabled (short MenuNumber);
  122.  
  123.    function PopUpIsEnabled (MenuNumber: INTEGER): BOOLEAN;
  124.  
  125.   MenuNumber specifies the pop-up menu number (from 1 to 255) which is queried in the current window.
  126.  
  127.   The function’s value returns true if the pop-up menu is enabled, and false if the pop-up menu is disabled.  If the current window doesn’t belong to your application, or if no windows are open, or if the pop-up menu does not exist in the current window, PopUpIsEnabled returns false.
  128.  
  129.   CONST                    {Menu and Menu Item status }
  130.     enabled       = true;  {enable the menu/item      }
  131.     disabled      = false; {disable the menu/item     }
  132.  
  133. Note: PopUpIsEnabled returns the pop-up menu’s state as though the pop-
  134.       up menu’s window is active.  This is the case even when the window
  135.      is deactivated and all the pop-up menus appear disabled.
  136.  
  137. ------------------------------------------------------------------------
  138.  
  139. CheckPopUp
  140. ``````````
  141. Display or hide a check mark to the left of a menu item.
  142.  
  143.    pascal void CheckPopUp (short MenuNumber, short ItemNumber,
  144.                  Boolean checked);
  145.  
  146.    procedure CheckPopUp (MenuNumber, ItemNumber: INTEGER;
  147.                  checked: BOOLEAN);
  148.  
  149.   MenuNumber specifies the pop-up menu number (from 1 to 255) that is affected in the current window.  If the current window doesn’t belong to your application, or if the specified pop-up menu doesn’t exist, CheckPopUp does nothing.
  150.  
  151.   ItemNumber specifies the pop-up menu item number (from 1 to 255) that is affected.  If the item number does not exist within the pop-up menu specified by MenuNumber, CheckPopUp does nothing.
  152.  
  153.   Checked specifies whether the pop-up menu item’s check mark is displayed or hidden.  The two constants that can be used for this purpose are on and off.  By default, pop-up menus can have only one item selected at a time.  Therefore, placing a check mark beside an item unchecks the previously checked item.  See the NewPopUp procedure if you want to override this behavior.
  154.  
  155.   To display characters other than the standard check mark, use the PopUpMark procedure.
  156.  
  157.   CONST          {Menu Item check mark status }
  158.     on  = true;  {check mark is on            }
  159.     off = false; {check mark is off           }
  160.  
  161. ------------------------------------------------------------------------
  162.  
  163. PopUpMark
  164. `````````
  165. Display or hide a special character to the left of a pop-up menu item’s name.  Use this procedure instead of CheckPopUp to display or hide characters other than the standard check mark.
  166.  
  167.    pascal void PopUpMark (short MenuNumber, short ItemNumber,
  168.                  char markChar);
  169.  
  170.    procedure PopUpMark (MenuNumber, ItemNumber: INTEGER;
  171.                  markChar: CHAR);
  172.  
  173.    MenuNumber specifies the pop-up menu number (from 1 to 255) that is affected in the current window.  If the current window doesn’t belong to your application, or if the specified pop-up menu doesn’t exist, PopUpMark does nothing.
  174.  
  175.    ItemNumber specifies the pop-up menu item number (from 1 to 255) that is affected.  If the item number does not exist within the pop-up menu specified by MenuNumber, PopUpMark does nothing.
  176.  
  177.    MarkChar specifies the character that is to be displayed.  By default, pop-up menus can have only one item selected at a time.  Therefore, placing a mark beside an item unmarks the previously marked item.  See the NewPopUp procedure if you want to override this behavior.  The following constants are available for pop-up menu marks:
  178.  
  179.   CONST                       {Menu Item characters              }
  180.     AppleChar   = char($14);  {Apple character                   }
  181.     CheckChar   = char($12);  {Check Mark character              }
  182.     DiamondChar = char($13);  {Diamond character                 }
  183.     DotChar     = char($A5);  {Dot (or bullet) character         }
  184.     NoChar      = char($00);  {No character (remove a character) }
  185.  
  186. ------------------------------------------------------------------------
  187.  
  188. GetPopUpMark
  189. ````````````
  190. Get a pop-up menu item’s special character that is optionally displayed to the left of an item’s name.
  191.  
  192.    pascal void GetPopUpMark (short MenuNumber, short ItemNumber,
  193.                  char *markChar);
  194.  
  195.    procedure GetPopUpMark (MenuNumber, ItemNumber: INTEGER;
  196.                  var markChar: CHAR);
  197.  
  198.   MenuNumber specifies the pop-up menu number (from 1 to 255) in the current window that contains the desired item.
  199.  
  200.   ItemNumber specifies the pop-up menu item number (from 1 to 255) whose mark character is obtained.
  201.  
  202.   MarkChar contains the “mark” character that is displayed to the left of the item’s name.  If no mark is displayed by the specified pop-up menu item, or if the specified pop-up menu or item doesn’t exist, MarkChar is set to null (char(0)).  The following are useful constants for testing menu marks:
  203.  
  204.   CONST                       {Menu Item characters              }
  205.     AppleChar   = char($14);  {Apple character                   }
  206.     CheckChar   = char($12);  {Check Mark character              }
  207.     DiamondChar = char($13);  {Diamond character                 }
  208.     DotChar     = char($A5);  {Dot (or bullet) character         }
  209.     NoChar      = char($00);  {No character (remove a character) }
  210.  
  211. ------------------------------------------------------------------------
  212.  
  213. PopUpIcon
  214. `````````
  215. Set a pop-up menu item’s icon.
  216.  
  217.    pascal void PopUpIcon (short MenuNumber, short ItemNumber,
  218.                  short IconSelector);
  219.  
  220.    procedure PopUpIcon (MenuNumber, ItemNumber, IconSelector: INTEGER);
  221.  
  222.   MenuNumber specifies the pop-up menu number (from 1 to 255) that is affected in the current window.  If the pop-up menu does not exist, PopUpIcon does nothing.
  223.  
  224.   ItemNumber specifies the pop-up menu item number (from 1 to 255) that is affected.  If the item number does not exist within the pop-up menu specified by MenuNumber, PopUpIcon does nothing.
  225.  
  226.   IconSelector identifies the icon that is used, and should be from 1 to 255.  The Menu Manager adds 256 to the number you state to specify a resource ID that is in the range of 257 to 511, so if you specify 28, resource ID 284 is used (28 + 256 = 284).  These icon resources are read from your application.  If Color QuickDraw is available on the Macintosh running your application, a ‘cicn’ (color) icon is used.  If a ‘cicn’ is not available (or Color QuickDraw is unavailable), an ‘ICON’ or ‘SICN’ is used.  Use zero (0) if you don’t want an icon displayed.
  227.  
  228.   Unlike the equivalent Macintosh toolbox routine, your menu item will remain unaffected if the specified icon can’t be found (i.e, empty space is not reserved in the menu).
  229.  
  230.   Be aware that the Menu Manager drawing a ‘cicn’ icon in color will do so even if the icon was created using 8-bit colors and the monitor is set to 4-bits.  This may produce unsatisfactory results.  If possible, use 4-bit colors or colors that translate well into 4-bit colors.
  231.  
  232. ------------------------------------------------------------------------
  233.  
  234. GetPopUpIcon
  235. ````````````
  236. Get a pop-up menu item’s icon number.
  237.  
  238.    pascal void GetPopUpIcon (short MenuNumber, short ItemNumber,
  239.                  short *IconSelector);
  240.  
  241.    procedure GetPopUpIcon (MenuNumber, ItemNumber: INTEGER;
  242.                  var IconSelector: INTEGER);
  243.  
  244.   MenuNumber specifies the pop-up menu number (from 1 to 255) that is affected in the current window that contains the desired menu item.
  245.  
  246.   ItemNumber specifies the pop-up menu item number (from 1 to 255) whose icon number is obtained.
  247.  
  248.   IconSelector contains the item’s icon number.  The Menu Manager automatically adds 256 to the IconSelector you specify, so an IconSelector of 28 means that resource ID 284 is used (28 + 256 = 284).  If an icon is not displayed by the specified pop-up menu item, IconSelector will be equal to zero.
  249.  
  250. ------------------------------------------------------------------------
  251.  
  252. PopUpStyle
  253. ``````````
  254. Set a pop-up menu item’s style.
  255.  
  256.    pascal void PopUpStyle (short MenuNumber, short ItemNumber,
  257.                  Style theStyle);
  258.  
  259.    procedure PopUpStyle (MenuNumber, ItemNumber: INTEGER;
  260.                  theStyle: Style);
  261.  
  262.   MenuNumber specifies the pop-up menu number (from 1 to 255) that is affected in the current window.  If the pop-up menu does not exist, PopUpStyle does nothing.
  263.  
  264.   ItemNumber specifies the pop-up menu item number (from 1 to 255) that is affected.  If the item number does not exist within the pop-up menu specified by MenuNumber, PopUpStyle does nothing.
  265.  
  266.   TheStyle specifies the style(s) in which the pop-up menu item is to be displayed.  Special character constants defined by the Font Manager are bold, italic, underline and shadow.  C programmers will use the font manager’s constants to specify a composite style, such as PopUpStyle(1,1, bold + outline) for bold and outlined, or PopUpStyle(1,1,0) for plain text.  Pascal programmers will use the font manager’s constants to specify a set, such as PopUpStyle(1,1,[bold,outline]) for bold and outlined, or PopUpStyle(1,1,[]) for plain text.
  267.  
  268. ------------------------------------------------------------------------
  269.  
  270. PopUpItemCount
  271. ``````````````
  272. Determine the number of items in a pop-up menu.
  273.  
  274.    pascal short PopUpItemCount (short MenuNumber);
  275.  
  276.    function PopUpItemCount (MenuNumber): INTEGER;
  277.  
  278.    MenuNumber specifies the pop-up menu number (from 1 to 255) you wish to query in the current window.
  279.  
  280.    The function’s value returns the number of items in the specified pop-up menu.  If the pop-up menu number does not exist, the function returns zero.
  281.  
  282. ------------------------------------------------------------------------
  283.  
  284. GetPopUpSelection
  285. `````````````````
  286. Determine the selected item in a pop-up menu.
  287.  
  288.    pascal short GetPopUpSelection (short MenuNumber);
  289.  
  290.    function GetPopUpSelection (MenuNumber: INTEGER): INTEGER;
  291.  
  292.   MenuNumber specifies the pop-up menu number (from 1 to 255) you wish to query in the current window.
  293.  
  294.   The function’s value returns the number of the pop-up menu item that is selected by having a “mark” (check mark or otherwise) beside it.  If you have defined your pop-up menu to allow multiple selections, PopUpItemCount returns the number of the first selected item.  If the pop-up menu number does not exist, the function returns zero.
  295.  
  296. ------------------------------------------------------------------------
  297.